/******************************************************************************
** $Id: dc_dmb_api.h,v 1.2 2009-12-15 19:26:39 let1 Exp $
**                 Proprietary and Confidential Information                  **
**                                                                           **
**                 Copyright (c) SigmaTel, Inc. Unpublished                  **
**                                                                           **
** This source code and the algorithms implemented therein constitute        **
** confidential information and may compromise trade secrets of SigmaTel,    **
** Inc. or its associates, and any unauthorized use thereof is prohibited.   **
**                                                                           **
******************************************************************************/
#ifndef _dc_dmb_h_
# define _dc_dmb_h_
/**************************************************************************//**
*  @file dc_dmb.h
*  @brief This file contains the API for DMB Manager. Please refer to the
*  Operating Environment reference manual for details.
******************************************************************************/
/******************************************************************************
*  FILE FORMAT: <PUBLIC>
*      1. INCLUDES 
*      2. ENUMERATIONS 
*      3. DEFINES
*      4. STRUCTURES
*      5. GLOBALS
*      6. PUBLIC FUNCTION PROTOTYPES
******************************************************************************/
/******************************************************************************
*  1. INCLUDES
******************************************************************************/
#include "dc_return_codes.h"
/******************************************************************************
*  2. ENUMERATIONS
******************************************************************************/
/******************************************************************************
*  3. DEFINES
******************************************************************************/
/**
** A terminal DC_DMB_NULL value indicates active creation of a corresponding 
** image. As such, the thread creating the image may be writing data actively
** to the terminal DMB in the linked list. In addition, at some future time, 
** subsequent DMBs may attach to the linked list.
*/
# define DC_DMB_NULL 0

/**
** A terminal DC_DMB_NULL_VALID value indicates that a terminal DMB in the 
** linked list if full of valid image data. This value also indicates that 
** the image creation is not complete, and, at some future time, subsequent 
** DMBs may add on to the linked list.
*/
# define DC_DMB_NULL_VALID 1

/**
** A terminal value of DC_DMB_NULL_EOP indicates that the corresponding image 
** creation is complete. Thus, the terminal DMB in the linked list is the final 
** DMB holding image data (i.e. no additional DMBs will join the linked list).
** Note that the terminal DMB is likely only partially filled with image data.
*/
# define DC_DMB_NULL_EOP 2

/**
** The return value of dc_dmb_status_get() or dc_dmb_status_get_ex() is set 
** when the page requested is not a valid DMB
*/
# define DC_DMB_PID_NOT_DMB 0xfffffffe

/**
** This macro verifies whether the forward link of the DMB given is 
** DC_DMB_NULL. DC_DMB_NULL indicates that the current DMB is the tail of
** the DMB list for the image. A process currently may be writing image data 
** to this current DMB.
**
** @param x - Input dynamic memory block (DMB)
**
** @return This macro returns TRUE if the DMB is DC_DMB_NULL, and returns 
** FALSE otherwise.
*/
# define DC_DMB_IS_NULL(_is_null_) (_is_null_ == DC_DMB_NULL)

/**
** This macro verifies whether the forward link of the DMB given is 
** DC_DMB_NULL_EOP. DC_DMB_NULL_EOP specifies that the current DMB contains 
** the last of the data for the image. The DMB is likely only partially filled 
** with image data.
**
** @param x - Input dynamic memory block (DMB)
**
** @return This macro returns TRUE if the DMB is DC_DMB_NULL_EOP, and returns 
** FALSE otherwise.
*/
# define DC_DMB_IS_NULL_EOP(_is_null_eop_) (_is_null_eop_ == DC_DMB_NULL_EOP)

/**
** This macro verifies whether the forward link of a given DMB is 
** DC_DMB_NULL_VALID. DC_DMB_NULL_VALID specifies that the current DMB is the 
** tail of the DMB list for the image and that the DMB is entirely filled with 
** valid image data.
**
** @param x - Input dynamic memory block (DMB)
**
** @return This macro returns TRUE if the DMB is DC_DMB_NULL_VALID, and 
** returns FALSE otherwise
*/
# define DC_DMB_IS_NULL_VALID(_null_valid_) (_null_valid_ == DC_DMB_NULL_VALID)

/**
** This macro checks if the two pages have equal forward links.
**
** @param x - Input dynamic memory block (DMB)
** @param y - Input dynamic memory block (DMB)
**
** @return Returns TRUE if the pages have equal forward links, FALSE 
** otherwise.
*/
# define DC_DMB_IS_EQUAL(_x_, _y_) (_x_==_y_)

/**
** This macro retrieves the next DMB reference given a DMB.
**
** @param _next_ - Input dynamic memory block (DMB)
**
** @return Returns the next DMB
*/
# define DC_DMB_SUBSEQUENT_GET(_next_) (_next_+1)

/**
** This macro determines whether the forward link of DMB given is 
** DC_DMB_NULL_VALID, DC_DMB_NULL_EOP, or DC_DMB_NULL_VALID.
**
** @param x - Input dynamic memory block (DMB)
**
** @return Returns TRUE if the page is any, FALSE otherwise.
*/
# define DC_DMB_NULL_ANY(x) ((DC_DMB_IS_NULL(x) || \
                              DC_DMB_IS_NULL_EOP(x) || \
                              DC_DMB_IS_NULL_VALID(x)))

/**
** This macro retrieves the dynamic memory block (DMB) page size for the
** system in kilobytes.
**
** @return Returns the DMB size in kilobytes.
*/
# define DC_DMB_PAGE_SIZE_KBYTE_GET (dc_dmb_size_get()/1024)


/*
** This inidates no limiting of DMB use (allocation)
*/
#define DC_DMB_UNLIMITED    0

/******************************************************************************
*  4. STRUCTURES
******************************************************************************/
typedef unsigned short DC_DMB;

typedef struct DC_DMB_PARAMS_STRUCT 
{
    UINT32 memSize; 
    UINT32 pageSize;
    UINT32 base;
} DC_DMB_PARAMS;

typedef struct
{
    UINT32 (*dc_dmb_free_get_filter)(UINT32 dmbAllocId, 
                                     UINT32 freePages,
                                     UINT32 totalPages);
    UINT32 (*dc_dmb_total_get_filter)(UINT32 dmbAllocId, 
                                      UINT32 freePages,
                                      UINT32 totalPages);
    boolean (*dc_dmb_alloc_filter)(UINT32 dmbAllocId,
                                   DC_DMB page,
                                   UINT32 freePages,
                                   UINT32 totalPages);
    void (*dc_dmb_free_filter)(UINT32 dmbAllocId,
                               DC_DMB page,
                               UINT32 freePages,
                               UINT32 totalPages);
} DC_DMB_FILTER;
/******************************************************************************
*  5. GLOBALS
******************************************************************************/
/******************************************************************************
*  6. PUBLIC FUNCTION PROTOTYPES
******************************************************************************/

/* DBGmon uses it's own definitions of these functions */
# ifndef WIN32 
DC_RETURN_CODE dc_dmb_init(DC_DMB_PARAMS *pMemLocal);
DC_RETURN_CODE dc_dmb_close(void);
DC_RETURN_CODE dc_dmb_filter_register(DC_DMB_FILTER *pFilter);
DC_RETURN_CODE dc_dmb_alloc (DC_DMB *newPage, 
                             DC_DMB previousPage, 
                             UINT32 dmbAllocId);
DC_RETURN_CODE dc_dmb_free(DC_DMB *nextPage, 
                           DC_DMB page);
DC_RETURN_CODE dc_dmb_next_get(DC_DMB *nextPage, 
                               DC_DMB page);
DC_RETURN_CODE dc_dmb_next_set (DC_DMB page, 
                                DC_DMB nextpage);
UINT8 *dc_dmb_address_get(DC_DMB page);
DC_RETURN_CODE dc_dmb_total_get (UINT32 *nPage, 
                       UINT32 dmbAllocId);
DC_RETURN_CODE dc_dmb_free_get(UINT32 *nPage, 
                     UINT32 dmbAllocId);
UINT32 dc_dmb_size_get(void);
UINT32 dc_dmb_system_size_get(void);
DC_RETURN_CODE dc_dmb_status_get (UINT32 *PID, 
                                  DC_DMB page);
DC_RETURN_CODE dc_dmb_status_get_ex (UINT32 *PID, 
                                     DC_DMB page, 
                                     UINT32 *alloc_time);
#  endif /* ifndef WIN32 */
#endif /* _dc_dmb_h_ */
